﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IHandleResources.cs" company="XamlNinja">
//   2011 Richard Griffin and Ollie Riches
// </copyright>
// <summary>
//   Interface defining RESTful operation that can be perform on a resource.
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace WP7Contrib.Communications
{
    using System;

    /// <summary>
    /// Interface defining RESTful operation that can be perform on a resource.
    /// </summary>
    public interface IHandleResources
    {
        /// <summary>
        /// Gets Type.
        /// </summary>
        ResourceType Type { get; }

        /// <summary>
        /// Defines the resource type to be used for the requests.
        /// </summary>
        /// <param name="type">
        /// The resource type being used - json, xml, soap.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources ForType(ResourceType type);

        /// <summary>
        /// Defines the url to be used for request operation types - GET, POST, PUT and DELETE
        /// </summary>
        /// <param name="url">
        /// The url endpoint for acessing the resource.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources UseUrl(string url);

        /// <summary>
        /// The url to use for GET operation.
        /// </summary>
        /// <param name="getUrl">
        /// The get url.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources UseUrlForGet(string getUrl);

        /// <summary>
        /// The url to use for POST operation.
        /// </summary>
        /// <param name="postUrl">
        /// The post url.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources UseUrlForPost(string postUrl);

        /// <summary>
        /// The url to use for PUT operation.
        /// </summary>
        /// <param name="putUrl">
        /// The put url.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources UseUrlForPut(string putUrl);

        /// <summary>
        /// The url to use for DELETE operation.
        /// </summary>
        /// <param name="deleteUrl">
        /// The delete url.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources UseUrlForDelete(string deleteUrl);

        /// <summary>
        /// The namespace associated with the resource - usually used with SOAP operations.
        /// </summary>
        /// <param name="prefix">
        /// The prefix.
        /// </param>
        /// <param name="namespace">
        /// The namespace to supplied for accessing the resource.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources WithNamespace(string prefix, string @namespace);

        /// <summary>
        /// The basic authentication used to access the resource.
        /// </summary>
        /// <param name="username">
        /// The username.
        /// </param>
        /// <param name="password">
        /// The password.
        /// </param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IHandleResources WithBasicAuthentication(string username, string password);

        /// <summary>
        ///  Allows the setting of how the json serializer will handle common serialization problems such
        /// as missing methods, reference loops etc.
        /// </summary>
        /// <param name="definitions">The defintions</param>
        /// <returns>Returns the instance of the interface - fluent interface style.</returns>
        IHandleResources WithHandlerDefinitions(JsonHandlerDefinitions definitions);
        
        /// <summary>
        /// Allows the setting of headers, many headers can be defined, but only one per 'Name'
        /// </summary>
        /// <param name="header">The header.</param>
        /// <returns>Returns the instance of the interface - fluent interface style.</returns>
        IHandleResources WithHeader(IHeader header);

        /// <summary>
        /// Executes a GET operation.
        /// </summary>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Get<TResponse>()
            where TResponse : class;

        /// <summary>
        /// Executes a GET operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Get<TResponse>(params object[] @params)
            where TResponse : class;

        /// <summary>
        /// Executes a PUT operation.
        /// </summary>
        /// <param name="resource">
        /// The resource to be sent with the request.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Put<TRequest, TResponse>(TRequest resource)
            where TRequest : class
            where TResponse : class;

        /// <summary>
        /// Executes a PUT operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        /// <param name="resource">
        /// The resource to be sent with the request.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Put<TRequest, TResponse>(TRequest resource, params object[] @params)
            where TRequest : class
            where TResponse : class;

        /// <summary>
        /// Executes a POST operation.
        /// </summary>
        /// <param name="resource">
        /// The resource to be sent with the request.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Post<TRequest, TResponse>(TRequest resource)
            where TRequest : class
            where TResponse : class;

        /// <summary>
        /// Executes a POST operation.
        /// </summary>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Post<TResponse>()
            where TResponse : class;

        /// <summary>
        /// Executes a POST operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        /// <param name="resource">
        /// The resource to be sent with the request.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Post<TRequest, TResponse>(TRequest resource, params object[] @params)
            where TRequest : class
            where TResponse : class;

        /// <summary>
        /// Executes a POST operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Post<TResponse>(params object[] @params)
            where TResponse : class;


        /// <summary>
        /// Executes a DELETE operation.
        /// </summary>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Delete<TResponse>()
            where TResponse : class;

        /// <summary>
        /// Executes a DELETE operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        /// <returns>
        /// Returns an observable response resource.
        /// </returns>
        IObservable<TResponse> Delete<TResponse>(params object[] @params)
            where TResponse : class;

        /// <summary>
        /// Executes a DELETE operation.
        /// </summary>
        void Delete();

        /// <summary>
        /// Executes a DELETE operation.
        /// </summary>
        /// <param name="params">
        /// The parameters required for the operation - theses will be combined into the url using a string format.
        /// </param>
        void Delete(params object[] @params);
    }
}